<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <link rel="stylesheet" href="http://www.petercorke.com/RVC/common/toolboxhelp.css">
    <title>M-File Help: tb_optparse</title>
  </head>
  <body>
  <table border="0" cellspacing="0" width="100%">
    <tr class="subheader">
      <td class="headertitle">M-File Help: tb_optparse</td>
      <td class="subheader-left"><a href="matlab:open tb_optparse">View code for tb_optparse</a></td>
    </tr>
  </table>
<h1>tb_optparse</h1><p><span class="helptopic">Standard option parser for Toolbox functions</span></p><p>
<strong>optout</strong> = <span style="color:red">tb_optparse</span>(<strong>opt</strong>, <strong>arglist</strong>) is a generalized option parser for
Toolbox functions.  <strong>opt</strong> is a structure that contains the names and
default values for the options, and <strong>arglist</strong> is a cell array containing
option parameters, typically it comes from VARARGIN.  It supports options
that have an assigned value, boolean or enumeration types (string or
int).

</p>
<p>
The software pattern is:

</p>
<pre style="width: 90%%;" class="examples">
function(a,&nbsp;b,&nbsp;c,&nbsp;varargin)
opt.foo&nbsp;=&nbsp;false;
opt.bar&nbsp;=&nbsp;true;
opt.blah&nbsp;=&nbsp;[];
opt.choose&nbsp;=&nbsp;{'this',&nbsp;'that',&nbsp;'other'};
opt.select&nbsp;=&nbsp;{'#no',&nbsp;'#yes'};
opt&nbsp;=&nbsp;tb_optparse(opt,&nbsp;varargin);
</pre>
<p>
Optional arguments to the function behave as follows:

</p>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> 'foo'</td> <td>sets opt.foo := true</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> 'nobar'</td> <td>sets opt.foo := false</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'blah',  3</td> <td>sets opt.blah := 3</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'blah', {x,y}</td> <td>sets opt.blah := {x,y}</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> 'that'</td> <td>sets opt.choose := 'that'</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> 'yes'</td> <td>sets opt.select := (the second element)</td></tr>
</table>
<p>
and can be given in any combination.

</p>
<p>
If neither of 'this', 'that' or 'other' are specified then opt.choose := 'this'.
Alternatively if:

</p>
<pre style="width: 90%%;" class="examples">
opt.choose&nbsp;=&nbsp;{[],&nbsp;'this',&nbsp;'that',&nbsp;'other'};
</pre>
<p>
then if neither of 'this', 'that' or 'other' are specified then opt.choose := []

</p>
<p>
If neither of 'no' or 'yes' are specified then opt.select := 1.

</p>
<p>
Note:

</p>
<ul>
  <li>That the enumerator names must be distinct from the field names.</li>
  <li>That only one value can be assigned to a field, if multiple values
are required they must placed in a cell array.</li>
  <li>To match an option that starts with a digit, prefix it with 'd_', so
the field 'd_3d' matches the option '3d'.</li>
  <li>OPT can be an object, rather than a structure, in which case the passed
options are assigned to properties.</li>
</ul>
<p>
The return structure is automatically populated with fields: verbose and
debug.  The following options are automatically parsed:

</p>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> 'verbose'</td> <td>sets opt.verbose := true</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> 'verbose=2'</td> <td>sets opt.verbose := 2 (very verbose)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> 'verbose=3'</td> <td>sets opt.verbose := 3 (extremeley verbose)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> 'verbose=4'</td> <td>sets opt.verbose := 4 (ridiculously verbose)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'debug',  N</td> <td>sets opt.debug := N</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> 'showopt'</td> <td>displays opt and arglist</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'setopt', S</td> <td>sets opt := S, if S.foo=4, and opt.foo is present, then
opt.foo is set to 4.</td></tr>
</table>
<p>
The allowable options are specified by the names of the fields in the
structure opt.  By default if an option is given that is not a field of
opt an error is declared.

</p>
<p>
[<strong>optout</strong>,<strong>args</strong>] = <span style="color:red">tb_optparse</span>(<strong>opt</strong>, <strong>arglist</strong>) as above but returns all the
unassigned options, those that don't match anything in <strong>opt</strong>, as a cell
array of all unassigned arguments in the order given in <strong>arglist</strong>.

</p>
<p>
[<strong>optout</strong>,<strong>args</strong>,<strong>ls</strong>] = <span style="color:red">tb_optparse</span>(<strong>opt</strong>, <strong>arglist</strong>) as above but if any
unmatched option looks like a MATLAB LineSpec (eg. 'r:') it is placed in <strong>ls</strong> rather
than in <strong>args</strong>.

</p>
<hr>

<table border="0" width="100%" cellpadding="0" cellspacing="0">
  <tr class="subheader" valign="top"><td>&nbsp;</td></tr></table>
<p class="copy">&copy; 1990-2014 Peter Corke.</p>
</body></html>